Tensors

Qtea Tensor

class qtealeaves.tensors.QteaTensor(links, ctrl='Z', are_links_outgoing=None, base_tensor_cls=None, dtype=<class 'numpy.complex128'>, device=None)

Dense tensor for Quantum Tea simulations using numpy or cupy as underlying arrays and linear algebra.

Arguments

linkslist of integers

Dimension along each link.

ctrlstr | scalar, optional

Initialization of tensor. Valid are “N” (uninitialized array), “Z” (zeros) “R”, “random” (random), “ground” for first element equal to one, or None (elem completely not set), scalar (the tensor is filled with that scalar value). Default to “Z”

are_links_outgoinglist of bools, optional

Used in symmetric tensors only

base_tensor_clsvalid dense quantum tea tensor or None, optional

Used in symmetric tensors only

dtypedata type, optional

Data type for numpy or cupy. Default to np.complex128

devicedevice specification, optional

Default to “cpu”. Available: “cpu”, “gpu”

add_update(other, factor_this=None, factor_other=None)

Inplace addition as self = factor_this * self + factor_other * other.

Arguments

othersame instance as self

Will be added to self. Unmodified on exit.

factor_thisscalar

Scalar weight for tensor self.

factor_otherscalar

Scalar weight for tensor other

are_equal(other, tol=1e-07)

Check if two tensors are equal.

property are_links_outgoing

Define property of outgoing links as property (always False).

assert_diagonal(tol=1e-07)

Check that tensor is a diagonal matrix up to tolerance.

assert_identity(tol=1e-07)

Check if tensor is an identity matrix.

assert_int_values(tol=1e-07)

Check that there are only integer values in the tensor.

assert_real_valued(tol=1e-07)

Check that all tensor entries are real-valued.

attach_dummy_link(position, is_outgoing=True)

Attach dummy link at given position (inplace update).

property base_tensor_cls

Base tensor class.

conj()

Return the complex conjugated in a new tensor.

conj_update()

Apply the complex conjugated to the tensor in place.

convert(dtype=None, device=None, stream=None)

Convert underlying array to the specified data type inplace.

Parameters

dtypenp.dtype, optional

Type to which you want to convert. If None, no conversion. Default to None.

devicestr, optional

Device where you want to send the QteaTensor. If None, no conversion. Default to None.

streamNone | cp.cuda.Stream

If not None, use a new stream for memory communication. Default to None (Use null stream).

static convert_operator_dict(op_dict, params=None, symmetries=None, generators=None, base_tensor_cls=None, dtype=<class 'numpy.complex128'>, device='cpu')

Iterate through an operator dict and convert the entries. Converts as well to rank-4 tensors.

Arguments

op_dictinstance of TNOperators

Contains the operators as xp.ndarray.

paramsdict, optional

To resolve operators being passed as callable.

symmetries: list, optional, for compatibility with symmetric tensors.

Must be empty list.

generatorslist, optional, for compatibility with symmetric tensors.

Must be empty list.

base_tensor_clsNone, optional, for compatibility with symmetric tensors.

No checks on this one here.

dtypedata type for xp, optional

Specify data type. Default to np.complex128

devicestr

Device for the simulation. Available “cpu” and “gpu” Default to “cpu”

Details

The conversion to rank-4 tensors is useful for future implementations, either to support adding interactions with a bond dimension greater than one between them or for symmetries. We add dummy links of dimension one. The order is (dummy link to the left, old link-1, old link-2, dummy link to the right).

convert_singvals(singvals, dtype=None, device=None, stream=None)

Convert the singular values via a tensor.

Parameters

dtypenp.dtype, optional

Type to which you want to convert. If None, no conversion. Default to None.

devicestr, optional

Device where you want to send the QteaTensor. If None, no conversion. Default to None.

streamNone | cp.cuda.Stream

If not None, use a new stream for memory communication. Default to None (Use null stream).

copy(dtype=None, device=None)

Make a copy of a tensor.

property device

Device where the tensor is stored.

diag(real_part_only=False, do_get=False)

Return the diagonal as array of rank-2 tensor.

dot(other)

Inner product of two tensors <self|other>.

property dtype

Data type of the underlying arrays.

property dtype_eps

Data type’s machine precision.

dtype_from_char(dtype)

Resolve data type from chars C, D, S, Z and optionally H.

static dummy_link(example_link)

Construct a dummy link. It is just the integer 1 if no symmetries are involved.

eig_api(matvec_func, links, conv_params, args_func=None, kwargs_func=None)

Interface to hermitian eigenproblem

Arguments

matvec_funccallable

Multiplies “matrix” with “vector”

linkslinks according to QteaTensor

Contain the dimension of the problem.

conv_paramsinstance of TNConvergenceParameters

Settings for eigenproblem with Arnoldi method.

args_func : arguments for matvec_func

kwargs_func : keyword arguments for matvec_func

Returns

eigenvalues : scalar

eigenvectors : instance of QteaTensor

eig_api_arpack(matvec_func, links, conv_params, args_func=None, kwargs_func=None)

Interface to hermitian eigenproblem via Arpack. Arguments see eig_api.

eig_api_qtea(matvec_func, conv_params, args_func=None, kwargs_func=None)

Interface to hermitian eigenproblem via qtealeaves.solvers. Arguments see eig_api.

eigvalsh()

Calculate eigendecomposition for a rank-2 tensor.

property elem

Elements of the tensor.

elementwise_abs_smaller_than(value)

Return boolean if each tensor element is smaller than value

expand_tensor(link, new_dim, ctrl='R')

Expand tensor along given link and to new dimension.

eye_like(link)

Generate identity matrix.

Arguments

selfinstance of QteaTensor

Extract data type etc from this one here.

linksame as returned by links property, here integer.

Dimension of the square, identity matrix.

flatten()

Returns flattened version (rank-1) of dense array in native array type.

static free_device_memory()

Free the unused device memory that is otherwise occupied by the cache. Otherwise cupy will keep the memory occupied for caching reasons.

classmethod from_elem_array(tensor, dtype=None, device=None)

New tensor from array

Arguments

tensorxp.ndarray

Array for new tensor.

dtypedata type, optional

Can allow to specify data type. If not None, it will convert. Default to None

fuse_links_update(fuse_low, fuse_high, is_link_outgoing=True)

Fuses one set of links to a single link (inplace-update).

Parameters

fuse_lowint

First index to fuse

fuse_highint

Last index to fuse.

Example: if you want to fuse links 1, 2, and 3, fuse_low=1, fuse_high=3. Therefore the function requires links to be already sorted before in the correct order.

get()

Get the whole array of a tensor to the host as tensor.

get_argsort_func()

Return callable to argsort function.

get_attr(*args)

High-risk resolve attribute for an operation on an elementary array.

get_diag_entries_as_int()

Return diagonal entries of rank-2 tensor as integer on host.

get_entry()

Get entry if scalar on host.

get_of(variable)

Run the get method to transfer to host on variable (same device as self).

get_sqrt_func()

Return callable to sqrt function.

get_submatrix(row_range, col_range)

Extract a submatrix of a rank-2 tensor for the given rows / cols.

getsizeof()

Size in memory (approximate, e.g., without considering meta data).

is_close_identity(tol=1e-07)

Check if rank-2 tensor is close to identity.

is_dtype_complex()

Check if data type is complex.

is_gpu_available()

Returns flag if GPU is available for this tensor class.

is_link_full(link_idx)

Check if the link at given index is at full bond dimension.

kron(other, idxs=None)

Perform the kronecker product between two tensors. By default, do it over all the legs, but you can also specify which legs should be kroned over. The legs over which the kron is not done should have the same dimension.

Parameters

otherQteaTensor

Tensor to kron with self

idxsTuple[int], optional

Indexes over which to perform the kron. If None, kron over all indeces. Default to None.

Returns

QteaTensor

The kronned tensor

Details

Performing the kronecker product between a tensor of shape (2, 3, 4) and a tensor of shape (1, 2, 3) will result in a tensor of shape (2, 6, 12).

To perform the normal kronecker product between matrices just pass rank-2 tensors.

To perform kronecker product between vectors first transfor them in rank-2 tensors of shape (1, -1)

Performing the kronecker product only along some legs means that along that leg it is an elementwise product and not a kronecker. For Example, if idxs=(0, 2) for the tensors of shapes (2, 3, 4) and (1, 3, 2) the output will be of shape (2, 3, 8).

property linear_algebra_library

Specification of the linear algebra library used as string numpy-cupy`.

property links

Here, as well dimension of tensor along each dimension.

mask_to_device(mask)

Send a mask to the device where the tensor is. (right now only CPU –> GPU, CPU –> CPU).

mask_to_host(mask)

Send a mask to the host. (right now only CPU –> GPU, CPU –> CPU).

classmethod mpi_bcast(tensor, comm, dtype, tn_mpi_types, root=0)

Broadcast tensor via MPI.

classmethod mpi_recv(from_, comm, tn_mpi_types, tensor_backend)

Send tensor via MPI.

Arguments

from_integer

MPI process to receive tensor from.

comm : instance of MPI communicator to be used

tn_mpi_typesdict

Dictionary mapping dtype to MPI data types.

tensor_backend : instance of TensorBackend

mpi_send(to_, comm, tn_mpi_types)

Send tensor via MPI.

Arguments

tointeger

MPI process to send tensor to.

comm : instance of MPI communicator to be used

tn_mpi_typesdict

Dictionary mapping dtype to MPI data types.

property ndim

Rank of the tensor.

norm()

Calculate the norm of the tensor <tensor|tensor>.

norm_sqrt()

Calculate the square root of the norm of the tensor, i.e., sqrt( <tensor|tensor>).

normalize()

Normalize tensor with sqrt(<tensor|tensor>).

permute_rows_cols_update(inds)

Permute rows and columns of rank-2 tensor with inds. Inplace update.

prepare_eig_api(conv_params)

Return xp variables for eigsh.

Returns

kwargsdict

Keyword arguments for eigs call. If initial guess can be passed, key “v0” is set with value None

LinearOperatorcallable

Function generating a LinearOperator

eigshcallable

Interface with actual call to eigsh

random_unitary(links)

Generate a random unitary matrix via performing a QR on a random tensor.

Arguments

selfinstance of QteaTensor

Extract data type etc from this one here.

linkssame as returned by links property, here integer.

Dimension of the tensors as [link[0], .., link[-1], link[0], .., link[-1]], random unitary matrix for contracting first/last half of legs with itself.

classmethod read(filehandle, dtype, device, base_tensor_cls, cmplx=True, order='F')

Read a tensor from file.

remove_dummy_link(position)

Remove the dummy link at given position (inplace update).

reshape(shape, **kwargs)

Reshape a tensor.

reshape_update(shape, **kwargs)

Reshape tensor dimensions inplace.

scale_link(link_weights, link_idx, do_inverse=False)

Scale tensor along one link at link_idx with weights.

Arguments

link_weightsnp.ndarray

Scalar weights, e.g., singular values.

link_idxint

Link which should be scaled.

do_inversebool, optional

If True, scale with inverse instead of multiplying with link weights. Default to False

Returns

updated_link : instance of QteaTensor

Details

The inverse implementation handles zeros correctly which have been introduced due to padding. Therefore, scale_link should be used over passing 1 / link_weights to this function.

scale_link_update(link_weights, link_idx, do_inverse=False)

Scale tensor along one link at link_idx with weights (inplace update).

Arguments

link_weightsnp.ndarray

Scalar weights, e.g., singular values.

link_idxint

Link which should be scaled.

do_inversebool, optional

If True, scale with inverse instead of multiplying with link weights. Default to False

Details

The inverse implementation handles zeros correctly which have been introduced due to padding. Therefore, scale_link_update should be used over passing 1 / link_weights to this function.

set_diagonal_entry(position, value)

Set the diagonal element in a rank-2 tensor (inplace update)

set_matrix_entry(idx_row, idx_col, value)

Set one element in a rank-2 tensor (inplace update)

static set_missing_link(links, max_dim, are_links_outgoing=None)

Calculate the property of a missing link in a list.

Arguments

linkslist

Contains data like returned by property links, except for one element being None

max_dimint

Maximal dimension of link allowed by convergence parameters or similar.

are_links_outgoinglist of bools

Indicates link direction for symmetry tensors only.

set_submatrix(row_range, col_range, tensor)

Set a submatrix of a rank-2 tensor for the given rows / cols.

set_subtensor_entry(corner_low, corner_high, tensor)

Set a subtensor (potentially expensive as looping explicitly, inplace update).

Arguments

corner_lowlist of ints

The lower index of each dimension of the tensor to set. Length must match rank of tensor self.

corner_highlist of ints

The higher index of each dimension of the tensor to set. Length must match rank of tensor self.

tensorQteaTensor

Tensor to be set as subtensor. Rank must match tensor self. Dimensions must match corner_high - corner_low.

Examples

To set the tensor of shape 2x2x2 in a larger tensor self of shape 8x8x8 the corresponing call is in comparison to a numpy syntax:

• self.set_subtensor_entry([2, 4, 2], [4, 6, 4], tensor)

• self[2:4, 4:6, 2:4] = tensor

Or with variables and rank-3 tensors

• self.set_subtensor_entry([a, b, c], [d, e, f], tensor)

• self[a:d, b:e, c:f] = tensor

To be able to work with all ranks, we currently avoid the numpy syntax in our implementation.

property shape

Dimension of tensor along each dimension.

split_qr(legs_left, legs_right, perm_left=None, perm_right=None, is_q_link_outgoing=True)

Split the tensor via a QR decomposition.

Parameters

selfinstance of QteaTensor

Tensor upon which apply the QR

legs_leftlist of int

Legs that will compose the rows of the matrix

legs_rightlist of int

Legs that will compose the columns of the matrix

perm_leftlist of int, optional

permutations of legs after the QR on left tensor

perm_rightlist of int, optional

permutation of legs after the QR on right tensor

Returns

tens_left: instance of QteaTensor

unitary tensor after the QR, i.e., Q.

tens_right: instance of QteaTensor

upper triangular tensor after the QR, i.e., R

split_qrte(tens_right, singvals_self, operator=None, conv_params=None, is_q_link_outgoing=True)

Perform an Truncated ExpandedQR decomposition, generalizing the idea of https://arxiv.org/pdf/2212.09782.pdf for a general bond expansion given the isometry center of the network on tens_left. It should be rather general for three-legs tensors, and thus applicable with any tensor network ansatz. Notice that, however, you do not have full control on the approximation, since you know only a subset of the singular values truncated.

Parameters

tens_left: xp.array

Left tensor

tens_right: xp.array

Right tensor

singvals_left: xp.array

Singular values array insisting on the link to the left of tens_left

operator: xp.array or None

Operator to contract with the tensors. If None, no operator is contracted

Returns

tens_left: ndarray

left tensor after the EQR

tens_right: ndarray

right tensor after the EQR

singvals: ndarray

singular values kept after the EQR

singvals_cutted: ndarray

subset of thesingular values cutted after the EQR, normalized with the biggest singval

split_svd(legs_left, legs_right, perm_left=None, perm_right=None, contract_singvals='N', conv_params=None, no_truncation=False, is_link_outgoing_left=True)

Perform a truncated Singular Value Decomposition by first reshaping the tensor into a legs_left x legs_right matrix, and permuting the legs of the ouput tensors if needed. If the contract_singvals = (‘L’, ‘R’) it takes care of renormalizing the output tensors such that the norm of the MPS remains 1 even after a truncation.

Parameters

selfinstance of QteaTensor

Tensor upon which apply the SVD

legs_leftlist of int

Legs that will compose the rows of the matrix

legs_rightlist of int

Legs that will compose the columns of the matrix

perm_leftlist of int, optional

permutations of legs after the SVD on left tensor

perm_rightlist of int, optional

permutation of legs after the SVD on right tensor

contract_singvals: string, optional

How to contract the singular values.

‘N’ : no contraction ‘L’ : to the left tensor ‘R’ : to the right tensor

conv_paramsTNConvergenceParameters, optional

Convergence parameters to use in the procedure. If None is given, then use the default convergence parameters of the TN. Default to None.

no_truncationboolean, optional

Allow to run without truncation Default to False (hence truncating by default)

Returns

tens_left: instance of QteaTensor

left tensor after the SVD

tens_right: instance of QteaTensor

right tensor after the SVD

singvals: xp.ndarray

singular values kept after the SVD

singvals_cut: xp.ndarray

singular values cut after the SVD, normalized with the biggest singval

sqrtm()

Calculate matrix-square-root for a rank-2 tensor.

stack_first_and_last_link(other)

Stack first and last link of tensor targeting MPS addition.

stack_link(other, link)

Stack two tensors along a given link.

Arguments

otherinstance of QteaTensor

Links must match self up to the specified link.

linkinteger

Stack along this link.

Returns

new_this : instance of :class:QteaTensor`

static static_is_gpu_available()

Returns flag if GPU is available for this tensor class.

subtensor_along_link(link, lower, upper)

Extract and return a subtensor select range (lower, upper) for one line.

tensordot(other, contr_idx)

Tensor contraction of two tensors along the given indices.

to_dense(true_copy=False)

Return dense tensor (if true_copy=False, same object may be returned).

to_dense_singvals(s_vals, true_copy=False)

Convert singular values to dense vector without symmetries.

trace(return_real_part=False, do_get=False)

Take the trace of a rank-2 tensor.

transpose(permutation)

Permute the links of the tensor and return new tensor.

transpose_update(permutation)

Permute the links of the tensor inplace.

vector_with_dim_like(dim, dtype=None)

Generate a vector in the native array of the base tensor.

write(filehandle, cmplx=None)

Write tensor in original Fortran compatible way.

Details

1. Number of links

2. Line with link dimensions

3. Entries of tensors line-by-line in column-major ordering.

zeros_like()

Get a tensor same as self but filled with zeros.

class qtealeaves.tensors.DataMoverNumpyCupy

Data mover to move QteaTensor between numpy and cupy

async_move(tensor, device)

Move the tensor tensor to the device device asynchronously with respect to the main computational stream

Parameters

tensor_AbstractTensor

The tensor to be moved

device: str

The device where to move the tensor

property device_memory

Current memory occupied in the device

sync_move(tensor, device)

Move the tensor tensor to the device device synchronously with the main computational stream

Parameters

tensor_AbstractTensor

The tensor to be moved

device: str

The device where to move the tensor

wait()

Put a barrier for the streams and wait them

class qtealeaves.tensors._process_svd_ctrl(svd_ctrl, max_bond_dim, shape, device, contract_singvals)

Process the svd_ctrl parameter for an SVD decomposition

Parameters

svd_ctrl: str

SVD identifier chosen by the user

max_bond_dimint

Maximum bond dimension

shape: Tuple[int]

Shape of the matrix to be split

device: str

Device where the splitting is taking place

contract_singvals: str

Where to contract the singvals

Return

str

The svd_ctrl after the double-check

Tensor Backend

class qtealeaves.tensors.TensorBackend(tensor_cls=<class 'qtealeaves.tensors.tensor.QteaTensor'>, base_tensor_cls=<class 'qtealeaves.tensors.tensor.QteaTensor'>, device='cpu', dtype=<class 'numpy.complex128'>, symmetry_injector=None, datamover=<qtealeaves.tensors.tensor.DataMoverNumpyCupy object>)

Defines the complete tensor backend to be used. Contains the tensor class, the base tensor class in case it is needed for symmetric tensors, the target device, and the data type.

Parameters

tensor_cls: _AbstractTensor, optional

Tensor class. Might be dense or symmetric. Default to QteaTensor

base_tensor_cls: _AbstractTensor, optional

The dense tensor class if tensor_cls was symmetric. Same as tensor_cls for dense tensors. Default to QteaTensor.

device: str, optional

Device of the tensors. Devices available depend on tensor_cls. The possible device available are: - “cpu” - “gpu” - “cgpu”, where the tensor network will be stored in the “cpu”,

but all the computational demanding tasks will be executed on the “gpu”.

Default to “cpu”.

dtype: np.dtype, optional

Type of the tensor network. Available types depends on ‘tensor_cls`. Default to np.complex128.

symmetry_injectorclass similar to AbelianSymmetryInjector or None

Provides inject_parse_symmetries, inject_trivial_symmetry, and inject_parse_sectors for parsing symmetries and sectors as well as providing the trivial symmetry representation. Default to None (only valid for no symmetries).

datamoverinstance of _AbstractDataMover

Data mover compatible with the base_tensor_cls Default to DataMoverNumpyCupy

property computational_device

Device where the computations are done

eye_like(link)

Create identity, unlike version in _AbstractQteaTensor, no existing tensor is required.

Arguments

linksame as returned by links property, here integer.

Dimension of the square, identity matrix.

property memory_device

Device where the tensor is stored

parse_sectors(params, sym)

Parse the sectors via a function which has to be passed by the user to __init__.

parse_symmetries(params)

Parse the symmetry via a function which has to be passed by the user to __init__.

tensor_cls_kwargs()

Returns the keywords arguments for an _AbstractQteaTensor.

trivial_symmetry()

Get trivial symmetry via a function which has to be passed by the user to __init__.

Abstract tensor

class qtealeaves.tensors._AbstractQteaTensor(links, ctrl='Z', are_links_outgoing=None, base_tensor_cls=None, dtype=None, device=None)

Tensor for Quantum Tea simulations.

Arguments

linkslist

Type of entries in list depends on tensor type and are either integers for dense tensors or some LinkType for symmetric tensors.

ctrlstr, optional

Initialization of tensor. Default to “Z”

are_links_outgoinglist of bools

Used in symmetric tensors only: direction of link in tensor. Length is same as rank of tensor.

base_tensor_clsvalid dense quantum tea tensor or None

Used in symmetric tensors only: class representing dense tensor

dtypedata type, optional

Valid data type for the underlying tensors.

devicedevice specification, optional

Valid device specification (depending on tensor).

abstract add_update(other, factor_this=None, factor_other=None)

Inplace addition as self = factor_this * self + factor_other * other.

abstract are_equal(other, tol=1e-07)

Check if two tensors are equal.

abstract property are_links_outgoing

Define property of outgoing links as property (always False).

assert_identical_irrep(link_idx)

Assert that specified link is identical irreps.

abstract assert_identity(tol=1e-07)

Check if tensor is an identity matrix.

assert_normalized(tol=1e-07)

Raise exception if norm is not 1 up to tolerance.

assert_unitary(links, tol=1e-07)

Raise exception if tensor is not unitary up to tolerance for given links.

abstract attach_dummy_link(position, is_outgoing=True)

Attach dummy link at given position (inplace update).

abstract property base_tensor_cls

Base tensor class.

abstract conj()

Return the complex conjugated in a new tensor.

abstract conj_update()

Apply the complex conjugate to the tensor in place.

abstract convert(dtype=None, device=None, stream=None)

Convert underlying array to the specified data type inplace.

abstract static convert_operator_dict(op_dict, params=None, symmetries=None, generators=None, base_tensor_cls=None, dtype=None, device=None)

Iterate through an operator dict and convert the entries.

Arguments

op_dictinstance of TNOperators

Contains the operators as xp.ndarray.

symmetries: list, optional, for compatability with symmetric tensors.

For symmetry, contains symmetries. Otherwise, must be empty list.

generatorslist, optional, for compatability with symmetric tensors.

For symmetries, contains generator of the symmetries as str for dict. Must be empty list.

base_tensor_clsNone, optional, for compatability with symmetric tensors.

For symmetries, must be valid base tensor class. Otherwise, no checks on this one here.

dtypedata type for xp, optional

Specify data type.

devicestr

Device for the simulation. Typically “cpu” and “gpu”, but depending on tensor backend.

abstract convert_singvals(singvals, dtype=None, device=None, stream=None)

Convert the singular values via a tensor.

abstract copy(dtype=None, device=None)

Make a copy of a tensor.

abstract property device

Device where the tensor is stored.

abstract dot(other)

Inner product of two tensors <self|other>.

abstract property dtype

Data type of the underlying arrays.

abstract property dtype_eps

Data type’s machine precision of the underlying arrays.

abstract dtype_from_char(dtype)

Resolve data type from chars C, D, S, Z and optionally H.

abstract static dummy_link(example_link)

Construct a dummy link. This method is particularly important for symmetries.

abstract eig_api(matvec_func, links, conv_params, args_func=None, kwargs_func=None)

Interface to hermitian eigenproblem

abstract expand_link_tensorpair(other, link_self, link_other, new_dim, ctrl='R')

Expand the link between a pair of tensors based on the ctrl parameter. “R” for random

abstract eye_like(link)

Generate identity matrix.

Arguments

selfinstance of QteaTensor

Extract data type etc from this one here.

linksame as returned by links property.

Dimension of the square, identity matrix.

flip_links_update(link_inds)

Flip irreps on given links (symmetric tensors only).

static free_device_memory()

Free the unused device memory that is otherwise occupied by the cache. This method SHOULD NOT free memory allocated for the computation.

abstract fuse_links_update(fuse_low, fuse_high, is_link_outgoing=True)

Fuses one set of links to a single link (inplace-update).

abstract get_entry()

Get entry if scalar on host.

abstract get_of(variable)

Run the get method to transfer to host on variable (same device as self).

abstract getsizeof()

Size in memory (approximate, e.g., without considering small meta data).

abstract is_close_identity(tol=1e-07)

Check if rank-2 tensor is close to identity.

abstract is_dtype_complex()

Check if data type is complex.

abstract is_identical_irrep(link_idx)

Check that the link at link_idx is identical irrep.

abstract is_link_full(link_idx)

Check if the link at given index is at full bond dimension.

abstract kron(other, idxs=None)

Perform the kronecker product between two tensors. By default, do it over all the legs, but you can also specify which legs should be kroned over. The legs over which the kron is not done should have the same dimension.

abstract property linear_algebra_library

Specification of the linear algebra library used as string.

abstract property links

Specification of link with full information to reconstruct link.

abstract property ndim

Rank of the tensor.

abstract norm()

Calculate the norm of the tensor <tensor|tensor>.

abstract norm_sqrt()

Calculate the square root of the norm of the tensor <tensor|tensor>.

abstract normalize()

Normalize tensor with sqrt(<tensor|tensor>).

abstract random_unitary(links)

Generate a random unitary tensor via performing a SVD on a random tensor, where a matrix dimension is specified with links. Tensor will be of the structure [link[0], .., link[-1], link[0], .., link[-1]].

abstract classmethod read(filehandle, dtype, device, base_tensor_cls, cmplx=True, order='F')

Read a tensor from file.

abstract remove_dummy_link(position)

Remove the dummy link at given position (inplace update).

abstract restrict_irreps(link_idx, sector)

Restrict, i.e., project, link to a sector (needed for symmetric tensors).

sanity_check()

Quick set of checks for tensor.

abstract scale_link(link_weights, link_idx, do_inverse=False)

Scale tensor along one link at link_idx with weights. Can do inverse, too.

abstract scale_link_update(link_weights, link_idx, do_inverse=False)

Scale tensor along one link at link_idx with weights (inplace update).

abstract set_diagonal_entry(position, value)

Set the diagonal element in a rank-2 tensor (inplace update)

abstract set_matrix_entry(idx_row, idx_col, value)

Set element in a rank-2 tensor (inplace update)

abstract static set_missing_link(links, max_dim, are_links_outgoing=None)

Calculate the property of a missing link in a list.

abstract property shape

Dimension of tensor along each dimension.

abstract split_link_deg_charge(link_idx)

Split a link into two, where one carries the degeneracy, the other the charge.

Arguments

link_idxint

Link to be split.

Returns

_AbstractQteaTensor

New tensor with link at position link_idx split into two links at link_idx (degeneracy) and link_idx + 1 (charge). Links originally after link_idx follow shifted by one index.

abstract split_qr(legs_left, legs_right, perm_left=None, perm_right=None, is_q_link_outgoing=True)

Split the tensor via a QR decomposition.

abstract split_qrte(tens_right, singvals_self, operator=None, conv_params=None, is_q_link_outgoing=True)

Split via a truncated expanded QR.

abstract split_svd(legs_left, legs_right, perm_left=None, perm_right=None, contract_singvals='N', conv_params=None, no_truncation=False, is_link_outgoing_left=True)

Split tensor via SVD for a bipartion of links.

abstract stack_link(other, link)

Stack two tensors along a given link.

abstract tensordot(other, contr_idx)

Tensor contraction of two tensors along the given indices.

abstract to_dense(true_copy=False)

Return dense tensor (if true_copy=False, same object may be returned).

abstract to_dense_singvals(s_vals, true_copy=False)

Convert singular values to dense vector without symmetries.

abstract trace(return_real_part=False, do_get=False)

Take the trace of a rank-2 tensor.

abstract trace_one_dim_pair(links)

Trace a pair of links with dimenion one. Inplace update.

abstract transpose(permutation)

Permute the links of the tensor and return new tensor.

abstract transpose_update(permutation)

Permute the links of the tensor inplace.

abstract write(filehandle, cmplx=None)

Write tensor.

abstract zeros_like()

Get a tensor with the same links as self but filled with zeros.

class qtealeaves.tensors._AbstractQteaBaseTensor(links, ctrl='Z', are_links_outgoing=None, base_tensor_cls=None, dtype=None, device=None)

abstract assert_diagonal(tol=1e-07)

Check that tensor is a diagonal matrix up to tolerance.

abstract assert_int_values(tol=1e-07)

Check that there are only integer values in the tensor.

abstract assert_real_valued(tol=1e-07)

Check that all tensor entries are real-valued.

concatenate_vectors(vectors, dtype, dim=None)

Concatenate vectors of the underlying numpy / cupy / torch / etc tensors.

Arguments*

vectorslist

List of one-dimensional arrays.

dtypedata type

Data type of concatenated vectors.

dimint | None

Total dimension of concatenated vectors. If None, calculated on the fly. Default to None

Returns

vecone-dimensional array of corresponding backend library, e.g., numpy ndarray

The elements in the list are concatenated in order, e.g., input [[1, 2], [6, 5, 3]] will result in [1, 2, 6, 5, 3].

mappingdict

Keys are the index of the individual vectors in the list vectors. Values are tuples with two integers with the lower and higher bound, e.g., {0 : (0, 2), 1: (2, 5)} for the example in vec in the previous return variable.

Details

Used to concatenate singular values for symmetric tensors in SVD, which is needed as jax and tensorflow do not support x[:] assignments.

abstract elementwise_abs_smaller_than(value)

Return boolean if each tensor element is smaller than value

expand_link_tensorpair(other, link_self, link_other, new_dim, ctrl='R')

Expand the link between a pair of tensors. If ctrl=”R”, the expansion is random

Arguments

other : instance of :class`QteaTensor`

link_selfint

Expand this link in self

link_otherint

Expand this link in other. Link must be a match (dimension etc.)

ctrlstr, optional

How to fill the extension. Default to “R” (random)

Returns

new_thisinstance of :class`QteaTensor`

Expanded version of self

new_otherinstance of :class`QteaTensor`

Expanded version of other

abstract expand_tensor(link, new_dim, ctrl='R')

Expand tensor along given link and to new dimension.

abstract flatten()

Returns flattened version (rank-1) of dense array in native array type.

abstract classmethod from_elem_array(tensor, dtype=None, device=None)

New tensor from array.

abstract get_argsort_func()

Return callable to argsort function.

abstract get_diag_entries_as_int()

Return diagonal entries of rank-2 tensor as integer on host.

abstract get_sqrt_func()

Return callable to sqrt function.

abstract get_submatrix(row_range, col_range)

Extract a submatrix of a rank-2 tensor for the given rows / cols.

is_identical_irrep(link_idx)

Check that the link at link_idx is identical irrep.

abstract mask_to_device(mask)

Send a mask to the device where the tensor is.

abstract mask_to_host(mask)

Send a mask to the host.

pad(link, new_dim, ctrl='R')

Pad a tensor along given link and to new dimension. It is a wapper around self.expand_tensor. The padding is added at the end.

Parameters

linkint

Link to expand

new_dimint

New dimension of the tensor

ctrlstr | scalar

Value for the padding

Returns

_AbstractQteaTensor

The padded tensor

abstract permute_rows_cols_update(inds)

Permute rows and columns of rank-2 tensor with inds. Inplace update.

abstract prepare_eig_api(conv_params)

Return variables for eigsh.

abstract reshape(shape, **kwargs)

Reshape a tensor.

abstract reshape_update(shape, **kwargs)

Reshape tensor dimensions inplace.

restrict_irreps(link_idx, sector)

Restrict, i.e., project, link to a sector (needed for symmetric tensors).

abstract set_submatrix(row_range, col_range, tensor)

Set a submatrix of a rank-2 tensor for the given rows / cols.

abstract set_subtensor_entry(corner_low, corner_high, tensor)

Set a subtensor (potentially expensive as looping explicitly, inplace update).

Arguments

corner_lowlist of ints

The lower index of each dimension of the tensor to set. Length must match rank of tensor self.

corner_highlist of ints

The higher index of each dimension of the tensor to set. Length must match rank of tensor self.

tensorQteaTensor

Tensor to be set as subtensor. Rank must match tensor self. Dimensions must match corner_high - corner_low.

Examples

To set the tensor of shape 2x2x2 in a larger tensor self of shape 8x8x8 the corresponing call is in comparison to a numpy syntax:

• self.set_subtensor_entry([2, 4, 2], [4, 6, 4], tensor)

• self[2:4, 4:6, 2:4] = tensor

Or with variables and rank-3 tensors

• self.set_subtensor_entry([a, b, c], [d, e, f], tensor)

• self[a:d, b:e, c:f] = tensor

To be able to work with all ranks, we currently avoid the numpy syntax in our implementation.

split_link_deg_charge(link_idx)

Split a link into two, where one carries the degeneracy, the other the charge.

abstract subtensor_along_link(link, lower, upper)

Extract and return a subtensor select range (lower, upper) for one line.

trace_one_dim_pair(links)

Trace a pair of links with dimenion one. Inplace update.

abstract vector_with_dim_like(dim, dtype=None)

Generate a vector in the native array of the base tensor.

class qtealeaves.tensors._AbstractDataMover

Abstract class for moving data between different devices

Class attributes

tensor_clsTuple[_AbstractTensor]

Tensor classes handled by the datamover

abstract async_move(tensor, device)

Move the tensor tensor to the device device asynchronously with respect to the main computational stream

Parameters

tensor_AbstractTensor

The tensor to be moved

device: str

The device where to move the tensor

check_tensor_cls_compatibility(tensor_cls)

Check if a tensor_cls can be handled by the datamover

Parameters

tensor_cls_AbstractTensor

The tensor class to check

move(tensor, device, sync=True)

Move the tensor tensor to the device device

Parameters

tensor_AbstractTensor

The tensor to be moved

device: str

The device where to move the tensor

syncbool, optional

If True, move synchronously. Otherwise asynchronously.

abstract sync_move(tensor, device)

Move the tensor tensor to the device device synchronously with the main computational stream

Parameters

tensor_AbstractTensor

The tensor to be moved

device: str

The device where to move the tensor

abstract wait()

Put a barrier for the streams and wait them